home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 April: Mac OS SDK / Dev.CD Apr 98 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Universal / Interfaces / PInterfaces / AppleGuide.p < prev    next >
Encoding:
Text File  |  1998-02-12  |  13.2 KB  |  472 lines  |  [TEXT/MPS ]
  1. {
  2.      File:        AppleGuide.p
  3.  
  4.      Contains:    Apple Guide Interfaces.
  5.  
  6.      Version:    Technology:    System 7.5
  7.                  Release:    Universal Interfaces 3.1
  8.  
  9.      Copyright:    ©1994-1998 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        Please include the the file and version information (from above) with
  12.                  the problem description.  Developers belonging to one of the Apple
  13.                  developer programs can submit bug reports to:
  14.  
  15.                      devsupport@apple.com
  16.  
  17. }
  18. {$IFC UNDEFINED UsingIncludes}
  19. {$SETC UsingIncludes := 0}
  20. {$ENDC}
  21.  
  22. {$IFC NOT UsingIncludes}
  23.  UNIT AppleGuide;
  24.  INTERFACE
  25. {$ENDC}
  26.  
  27. {$IFC UNDEFINED __APPLEGUIDE__}
  28. {$SETC __APPLEGUIDE__ := 1}
  29.  
  30. {$I+}
  31. {$SETC AppleGuideIncludes := UsingIncludes}
  32. {$SETC UsingIncludes := 1}
  33.  
  34. {$IFC UNDEFINED __MACTYPES__}
  35. {$I MacTypes.p}
  36. {$ENDC}
  37. {$IFC UNDEFINED __APPLEEVENTS__}
  38. {$I AppleEvents.p}
  39. {$ENDC}
  40. {$IFC UNDEFINED __FILES__}
  41. {$I Files.p}
  42. {$ENDC}
  43.  
  44.  
  45.  
  46. {$PUSH}
  47. {$ALIGN MAC68K}
  48. {$LibExport+}
  49.  
  50. {  Types }
  51.  
  52. TYPE
  53.     AGRefNum                            = UInt32;
  54.     AGCoachRefNum                        = UInt32;
  55.     AGContextRefNum                        = UInt32;
  56.     AGAppInfoPtr = ^AGAppInfo;
  57.     AGAppInfo = RECORD
  58.         eventId:                AEEventID;
  59.         refCon:                    LONGINT;
  60.         contextObj:                Ptr;                                    {  private system field }
  61.     END;
  62.  
  63.     AGAppInfoHdl                        = ^AGAppInfoPtr;
  64. {$IFC TYPED_FUNCTION_POINTERS}
  65.     CoachReplyProcPtr = FUNCTION(VAR pRect: Rect; name: Ptr; refCon: LONGINT): OSErr;
  66. {$ELSEC}
  67.     CoachReplyProcPtr = ProcPtr;
  68. {$ENDC}
  69.  
  70. {$IFC TYPED_FUNCTION_POINTERS}
  71.     ContextReplyProcPtr = FUNCTION(pInputData: Ptr; inputDataSize: Size; VAR ppOutputData: Ptr; VAR pOutputDataSize: Size; hAppInfo: AGAppInfoHdl): OSErr;
  72. {$ELSEC}
  73.     ContextReplyProcPtr = ProcPtr;
  74. {$ENDC}
  75.  
  76.     CoachReplyUPP = UniversalProcPtr;
  77.     ContextReplyUPP = UniversalProcPtr;
  78.  
  79. CONST
  80.     uppCoachReplyProcInfo = $00000FE0;
  81.     uppContextReplyProcInfo = $0000FFE0;
  82.  
  83. FUNCTION NewCoachReplyProc(userRoutine: CoachReplyProcPtr): CoachReplyUPP;
  84.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  85.     INLINE $2E9F;
  86.     {$ENDC}
  87.  
  88. FUNCTION NewContextReplyProc(userRoutine: ContextReplyProcPtr): ContextReplyUPP;
  89.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  90.     INLINE $2E9F;
  91.     {$ENDC}
  92.  
  93. FUNCTION CallCoachReplyProc(VAR pRect: Rect; name: Ptr; refCon: LONGINT; userRoutine: CoachReplyUPP): OSErr;
  94.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  95.     INLINE $205F, $4E90;
  96.     {$ENDC}
  97.  
  98. FUNCTION CallContextReplyProc(pInputData: Ptr; inputDataSize: Size; VAR ppOutputData: Ptr; VAR pOutputDataSize: Size; hAppInfo: AGAppInfoHdl; userRoutine: ContextReplyUPP): OSErr;
  99.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  100.     INLINE $205F, $4E90;
  101.     {$ENDC}
  102. {  Constants }
  103.  
  104.  
  105.  
  106. CONST
  107.     kAGDefault                    = 0;
  108.     kAGFrontDatabase            = 1;
  109.     kAGNoMixin                    = -1;
  110.  
  111.  
  112.     kAGViewFullHowdy            = 1;                            {  Full-size Howdy }
  113.     kAGViewTopicAreas            = 2;                            {  Full-size Topic Areas }
  114.     kAGViewIndex                = 3;                            {  Full-size Index Terms }
  115.     kAGViewLookFor                = 4;                            {  Full-size Look-For (Search) }
  116.     kAGViewSingleHowdy            = 5;                            {  Single-list-size Howdy }
  117.     kAGViewSingleTopics            = 6;                            {  Single-list-size Topics }
  118.  
  119.  
  120.     kAGFileMain                    = 'poco';
  121.     kAGFileMixin                = 'mixn';
  122.  
  123. {  To test against AGGetAvailableDBTypes }
  124.     kAGDBTypeBitAny                = $00000001;
  125.     kAGDBTypeBitHelp            = $00000002;
  126.     kAGDBTypeBitTutorial        = $00000004;
  127.     kAGDBTypeBitShortcuts        = $00000008;
  128.     kAGDBTypeBitAbout            = $00000010;
  129.     kAGDBTypeBitOther            = $00000080;
  130.  
  131.  
  132.  
  133. TYPE
  134.     AGStatus                            = UInt16;
  135. {  Returned by AGGetStatus }
  136.  
  137. CONST
  138.     kAGIsNotRunning                = 0;
  139.     kAGIsSleeping                = 1;
  140.     kAGIsActive                    = 2;
  141.  
  142.  
  143.  
  144. TYPE
  145.     AGWindowKind                        = UInt16;
  146. {  Returned by AGGetFrontWindowKind }
  147.  
  148. CONST
  149.     kAGNoWindow                    = 0;
  150.     kAGAccessWindow                = 1;
  151.     kAGPresentationWindow        = 2;
  152.  
  153. {  Error Codes }
  154.  
  155. {  Not an enum, because other OSErrs are valid. }
  156.  
  157. TYPE
  158.     AGErr                                = SInt16;
  159. {  Apple Guide error codes }
  160.  
  161. CONST
  162.                                                                 {  -------------------- Apple event reply codes }
  163.     kAGErrUnknownEvent            = -2900;
  164.     kAGErrCantStartup            = -2901;
  165.     kAGErrNoAccWin                = -2902;
  166.     kAGErrNoPreWin                = -2903;
  167.     kAGErrNoSequence            = -2904;
  168.     kAGErrNotOopsSequence        = -2905;
  169.     kAGErrReserved06            = -2906;
  170.     kAGErrNoPanel                = -2907;
  171.     kAGErrContentNotFound        = -2908;
  172.     kAGErrMissingString            = -2909;
  173.     kAGErrInfoNotAvail            = -2910;
  174.     kAGErrEventNotAvailable        = -2911;
  175.     kAGErrCannotMakeCoach        = -2912;
  176.     kAGErrSessionIDsNotMatch    = -2913;
  177.     kAGErrMissingDatabaseSpec    = -2914;                        {  -------------------- Coach's Chalkboard reply codes }
  178.     kAGErrItemNotFound            = -2925;
  179.     kAGErrBalloonResourceNotFound = -2926;
  180.     kAGErrChalkResourceNotFound    = -2927;
  181.     kAGErrChdvResourceNotFound    = -2928;
  182.     kAGErrAlreadyShowing        = -2929;
  183.     kAGErrBalloonResourceSkip    = -2930;
  184.     kAGErrItemNotVisible        = -2931;
  185.     kAGErrReserved32            = -2932;
  186.     kAGErrNotFrontProcess        = -2933;
  187.     kAGErrMacroResourceNotFound    = -2934;                        {  -------------------- API reply codes }
  188.     kAGErrAppleGuideNotAvailable = -2951;
  189.     kAGErrCannotInitCoach        = -2952;
  190.     kAGErrCannotInitContext        = -2953;
  191.     kAGErrCannotOpenAliasFile    = -2954;
  192.     kAGErrNoAliasResource        = -2955;
  193.     kAGErrDatabaseNotAvailable    = -2956;
  194.     kAGErrDatabaseNotOpen        = -2957;
  195.     kAGErrMissingAppInfoHdl        = -2958;
  196.     kAGErrMissingContextObject    = -2959;
  197.     kAGErrInvalidRefNum            = -2960;
  198.     kAGErrDatabaseOpen            = -2961;
  199.     kAGErrInsufficientMemory    = -2962;
  200.  
  201. {  Events }
  202.  
  203. {  Not an enum because we want to make assignments. }
  204.  
  205. TYPE
  206.     AGEvent                                = UInt32;
  207. {  Handy events for AGGeneral. }
  208.  
  209. CONST
  210.                                                                 {  Panel actions (Require a presentation window). }
  211.     kAGEventDoCoach                = 'doco';
  212.     kAGEventDoHuh                = 'dhuh';
  213.     kAGEventGoNext                = 'gonp';
  214.     kAGEventGoPrev                = 'gopp';
  215.     kAGEventHidePanel            = 'pahi';
  216.     kAGEventReturnBack            = 'gobk';
  217.     kAGEventShowPanel            = 'pash';
  218.     kAGEventTogglePanel            = 'patg';
  219.  
  220. {  Functions }
  221.  
  222. {
  223.    AGClose
  224.    Close the database associated with the AGRefNum.
  225. }
  226.  
  227. FUNCTION AGClose(VAR refNum: AGRefNum): AGErr;
  228.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  229.     INLINE $7011, $AA6E;
  230.     {$ENDC}
  231. {
  232.    AGGeneral
  233.    Cause various events to happen.
  234. }
  235.  
  236. FUNCTION AGGeneral(refNum: AGRefNum; theEvent: AGEvent): AGErr;
  237.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  238.     INLINE $700D, $AA6E;
  239.     {$ENDC}
  240. {
  241.    AGGetAvailableDBTypes
  242.    Return the database types available for this application.
  243. }
  244.  
  245. FUNCTION AGGetAvailableDBTypes: UInt32;
  246.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  247.     INLINE $7008, $AA6E;
  248.     {$ENDC}
  249. {
  250.    AGGetFrontWindowKind
  251.    Return the kind of the front window.
  252. }
  253.  
  254. FUNCTION AGGetFrontWindowKind(refNum: AGRefNum): AGWindowKind;
  255.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  256.     INLINE $700C, $AA6E;
  257.     {$ENDC}
  258. {
  259.    AGGetFSSpec
  260.    Return the FSSpec for the AGRefNum.
  261. }
  262.  
  263. FUNCTION AGGetFSSpec(refNum: AGRefNum; VAR fileSpec: FSSpec): AGErr;
  264.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  265.     INLINE $700F, $AA6E;
  266.     {$ENDC}
  267. {
  268.    AGGetStatus
  269.    Return the status of Apple Guide.
  270. }
  271.  
  272. FUNCTION AGGetStatus: AGStatus;
  273.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  274.     INLINE $7009, $AA6E;
  275.     {$ENDC}
  276. {
  277.    AGInstallCoachHandler
  278.    Install a Coach object location query handler.
  279. }
  280.  
  281. FUNCTION AGInstallCoachHandler(coachReplyProc: CoachReplyUPP; refCon: LONGINT; VAR resultRefNum: AGCoachRefNum): AGErr;
  282.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  283.     INLINE $7012, $AA6E;
  284.     {$ENDC}
  285. {
  286.    AGInstallContextHandler
  287.    Install a context check query handler.
  288. }
  289.  
  290. FUNCTION AGInstallContextHandler(contextReplyProc: ContextReplyUPP; eventID: AEEventID; refCon: LONGINT; VAR resultRefNum: AGContextRefNum): AGErr;
  291.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  292.     INLINE $7013, $AA6E;
  293.     {$ENDC}
  294. {
  295.    AGIsDatabaseOpen
  296.    Return true if the database associated with the AGRefNum is open.
  297. }
  298.  
  299. FUNCTION AGIsDatabaseOpen(refNum: AGRefNum): BOOLEAN;
  300.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  301.     INLINE $7006, $AA6E;
  302.     {$ENDC}
  303. {
  304.    AGOpen
  305.    Open a guide database.
  306. }
  307.  
  308. FUNCTION AGOpen(fileSpec: ConstFSSpecPtr; flags: UInt32; mixinControl: Handle; VAR resultRefNum: AGRefNum): AGErr;
  309.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  310.     INLINE $7001, $AA6E;
  311.     {$ENDC}
  312. {
  313.    AGOpenWithSearch
  314.    Open a guide database and preset a search string.
  315. }
  316.  
  317. FUNCTION AGOpenWithSearch(fileSpec: ConstFSSpecPtr; flags: UInt32; mixinControl: Handle; searchString: Str255; VAR resultRefNum: AGRefNum): AGErr;
  318.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  319.     INLINE $7002, $AA6E;
  320.     {$ENDC}
  321. {
  322.    AGOpenWithSequence
  323.    Open a guide database and display a presentation window sequence.
  324. }
  325.  
  326. FUNCTION AGOpenWithSequence(fileSpec: ConstFSSpecPtr; flags: UInt32; mixinControl: Handle; sequenceID: INTEGER; VAR resultRefNum: AGRefNum): AGErr;
  327.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  328.     INLINE $7004, $AA6E;
  329.     {$ENDC}
  330. {
  331.    AGOpenWithView
  332.    Open a guide database and override the default view.
  333. }
  334.  
  335. FUNCTION AGOpenWithView(fileSpec: ConstFSSpecPtr; flags: UInt32; mixinControl: Handle; viewNum: INTEGER; VAR resultRefNum: AGRefNum): AGErr;
  336.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  337.     INLINE $7005, $AA6E;
  338.     {$ENDC}
  339. {
  340.    AGQuit
  341.    Make Apple Guide quit.
  342. }
  343.  
  344. FUNCTION AGQuit: AGErr;
  345.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  346.     INLINE $7010, $AA6E;
  347.     {$ENDC}
  348. {
  349.    AGRemoveCoachHandler
  350.    Remove the Coach object location query handler.
  351. }
  352.  
  353. FUNCTION AGRemoveCoachHandler(VAR resultRefNum: AGCoachRefNum): AGErr;
  354.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  355.     INLINE $7014, $AA6E;
  356.     {$ENDC}
  357. {
  358.    AGRemoveContextHandler
  359.    Remove the context check query handler.
  360. }
  361.  
  362. FUNCTION AGRemoveContextHandler(VAR resultRefNum: AGContextRefNum): AGErr;
  363.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  364.     INLINE $7015, $AA6E;
  365.     {$ENDC}
  366. {
  367.    AGStart
  368.    Start up Apple Guide in the background.
  369. }
  370.  
  371. FUNCTION AGStart: AGErr;
  372.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  373.     INLINE $700A, $AA6E;
  374.     {$ENDC}
  375.  
  376.  
  377. {  typedef's }
  378.  
  379.  
  380. TYPE
  381.     AGFileFSSpecType                    = FSSpec;
  382.     AGFileFSSpecTypePtr                 = ^AGFileFSSpecType;
  383.     AGFileSelectorCountType                = INTEGER;
  384.     AGFileSelectorIndexType                = INTEGER;
  385.     AGFileSelectorType                    = OSType;
  386.     AGFileSelectorValueType                = LONGINT;
  387.     AGFileDBType                        = INTEGER;
  388.     AGFileDBMenuNamePtr                    = Str63;
  389.     AGFileDBScriptType                    = INTEGER;
  390.     AGFileDBRegionType                    = INTEGER;
  391.     AGFileMajorRevType                    = INTEGER;
  392.     AGFileMinorRevType                    = INTEGER;
  393.     AGFileCountType                        = INTEGER;
  394. {  Database types (for AGFileDBType parameter). }
  395.  
  396. CONST
  397.     kAGFileDBTypeAny            = 0;
  398.     kAGFileDBTypeHelp            = 1;
  399.     kAGFileDBTypeTutorial        = 2;
  400.     kAGFileDBTypeShortcuts        = 3;
  401.     kAGFileDBTypeAbout            = 4;
  402.     kAGFileDBTypeOther            = 8;
  403.  
  404.  
  405.  
  406. FUNCTION AGFileGetDBMenuName({CONST}VAR fileSpec: FSSpec; VAR menuItemNameString: Str63): OSErr;
  407. {  Get the database type. }
  408. FUNCTION AGFileGetDBType({CONST}VAR fileSpec: FSSpec; VAR databaseType: AGFileDBType): OSErr;
  409. {
  410.    Get the version of the software
  411.    that created this database.
  412. }
  413. FUNCTION AGFileGetDBVersion({CONST}VAR fileSpec: FSSpec; VAR majorRev: AGFileMajorRevType; VAR minorRev: AGFileMinorRevType): OSErr;
  414. {  Get the database script and region information. }
  415. FUNCTION AGFileGetDBCountry({CONST}VAR fileSpec: FSSpec; VAR script: AGFileDBScriptType; VAR region: AGFileDBRegionType): OSErr;
  416. {  Return the number of selectors in database. }
  417. FUNCTION AGFileGetSelectorCount({CONST}VAR fileSpec: FSSpec): AGFileSelectorCountType;
  418. {
  419.    Get the i-th database selector (1 to AGFileSelectorCountType)
  420.    and its value.
  421. }
  422. FUNCTION AGFileGetSelector({CONST}VAR fileSpec: FSSpec; selectorNumber: AGFileSelectorIndexType; VAR selector: AGFileSelectorType; VAR value: AGFileSelectorValueType): OSErr;
  423. {  Return true if database is mixin. }
  424. FUNCTION AGFileIsMixin({CONST}VAR fileSpec: FSSpec): BOOLEAN;
  425. {
  426.    Return the number of database files
  427.    of the specified databaseType and main/mixin.
  428.    Any file creator is acceptible,
  429.    but type must be kAGFileMain or kAGFileMixin.
  430. }
  431. FUNCTION AGFileGetDBCount(vRefNum: INTEGER; dirID: LONGINT; databaseType: AGFileDBType; wantMixin: BOOLEAN): AGFileCountType;
  432. {
  433.    Get the FSSpec for the dbIndex-th database
  434.    of the specified databaseType and main/mixin.
  435.    Any file creator is acceptible,
  436.    but type must be kAGFileMain or kAGFileMixin.
  437. }
  438. FUNCTION AGFileGetIndDB(vRefNum: INTEGER; dirID: LONGINT; databaseType: AGFileDBType; wantMixin: BOOLEAN; dbIndex: INTEGER; VAR fileSpec: FSSpec): OSErr;
  439. {
  440.    This selector must match with the application
  441.    creator in order for this file to appear in the 
  442.    application's Help menu. Ignored for mixin files
  443.    because they never appear in the Help menu anyway.
  444.    If empty (zeros), will appear in the Help menu
  445.    of any host application.
  446. }
  447. FUNCTION AGFileGetHelpMenuAppCreator({CONST}VAR fileSpec: FSSpec; VAR helpMenuAppCreator: OSType): OSErr;
  448. {
  449.    This selector must match in the main and mixin
  450.    files in order for the mixin to mix-in with the main.
  451.    Empty (zeros) selectors are valid matches.
  452.    A '****' selector will mix-in with any main.
  453. }
  454. FUNCTION AGFileGetMixinMatchSelector({CONST}VAR fileSpec: FSSpec; VAR mixinMatchSelector: OSType): OSErr;
  455. {
  456.    This is the text of the balloon for the
  457.    Help menu item for this database.
  458. }
  459. FUNCTION AGFileGetHelpMenuBalloonText({CONST}VAR fileSpec: FSSpec; VAR helpMenuBalloonString: Str255): OSErr;
  460.  
  461. FUNCTION AGGetSystemDB(databaseType: AGFileDBType; wantMixin: BOOLEAN; VAR pFileSpec: FSSpec): OSErr;
  462. {$ALIGN RESET}
  463. {$POP}
  464.  
  465. {$SETC UsingIncludes := AppleGuideIncludes}
  466.  
  467. {$ENDC} {__APPLEGUIDE__}
  468.  
  469. {$IFC NOT UsingIncludes}
  470.  END.
  471. {$ENDC}
  472.